The IDL RPC library contains several C language interface functions that facilitate communication between your application and IDL. There are functions to register and unregister clients, set timeouts, get and set the value of IDL variables, send commands to the IDL server, and cause the server to exit.
int IDL_RPCCleanup( CLIENT *pClient, int iKill)
Use this function to release the resources associated with the given CLIENT structure or to kill the IDL RPC server.
A pointer to the CLIENT structure for the client/server connection to be disconnected.
Set iKill to a non-zero value to kill the server when the connection is broken.
This function returns 1 on success, or 0 on failure.
void IDL_RPCDeltmp( IDL_VPTR vTmp)
Use this function to de-allocate all dynamic memory associated with the IDL_VPTR that is passed into the function. Once this function returns, any dynamic portion of vTmp is deallocated and should not be referenced.
The variable that will be de-allocated.
None.
int IDL_RPCExecuteStr(CLIENT *pClient, char * pCommand)
Use this function to send IDL commands to the IDL RPC server. The command is executed just as if it had been entered from the IDL command line.
This function cannot be used to send multiple line commands and will return an error if a “$” is detected at the end of the command string. It will also return an error if “$” is the first character, since this would spawn an interactive process and hang the IDL RPC server.
A pointer to the CLIENT structure that corresponds to the desired IDL session.
A null-terminated IDL command string.
This function returns the following values:
1 — Success.
0 — Invalid command string.
For all other errors, the value of !ERROR_STATE.CODE is returned. This number could be passed as an argument to the IDL function STRMESSAGE() to determine the exact cause of the error.
Note: When an error occurs in IDL, the !ERROR_STATE system variable remains populated with that error until it is cleared or another error occurs. IDL_RPCExecuteStr() merely returns the error code stored in !ERROR_STATE. To clear the error state, call:
MESSAGE, /RESET
IDL_VPTR IDL_RPCGetMainVariable(CLIENT *pClient, char *Name)
Call this function to get the value of an IDL RPC server main level variable referenced by the name contained in Name. IDL_RPCGetMainVariable will then return a pointer to an IDL_VARIABLE structure that contains the value of the variable.
A pointer to the CLIENT structure that corresponds to the desired IDL session.
The name of the variable to find.
On success, this function returns a pointer to an IDL_VARIABLE structure that contains the value of the desired IDL RPC main level variable. On failure this function returns NULL.
Note that the returned variable is marked as temporary and should be deleted when the variable is no longer needed.
IDL_VPTR IDL_RPCGettmp(void)
Use this function to create an IDL_VPTR to a dynamically allocated IDL_VARIABLE structure. When you are finished with this variable, pass it to IDL_RPCDeltmp() to free any memory allocated by the variable.
None.
On success, this function returns an IDL_VPTR. On failure, it returns NULL.
IDL_VPTR IDL_RPCGetVariable(CLIENT *pClient, char *Name)
Use this function to get a pointer to an IDL_VARIABLE structure that contains the value of an IDL RPC server variable referenced by Name. The current scope of the IDL program is used to get the value of the variable.
A pointer to the CLIENT structure that corresponds to the desired IDL session.
The name of the variable to find.
On success, this function returns a pointer to an IDL_VARIABLE structure that contains the value of the desired IDL RPC variable. On failure this function returns NULL.
Note that the returned variable is marked as temporary and should be deleted when the variable is no longer needed. For more information on IDL RPC variables, see Client Variables.
IDL_VPTR IDL_RPCImportArray(int n_dim, IDL_MEMINT dim[], int type, UCHAR *data, IDL_ARRAY_FREE_CB free_cb)
Use this function to create an IDL array variable whose data the server supplies, rather than having the client API allocate the data space.
The number of dimensions in the array.
An array of IDL_MAX_ARRAY_DIM elements, containing the size of each dimension.
The IDL type code describing the data.
A pointer to your array data.
If non-NULL, free_cb is a pointer to a function that will be called when the IDL RPC client routines frees the array. This feature gives the caller a sure way to know when the data is no longer referenced. Use the called function to perform any required cleanup, such as freeing dynamic memory or releasing shared or mapped memory.
An IDL_VPTR that points to an IDL_VARIABLE structure containing a reference to the imported array. This function returns NULL if the operation was unsuccessful.
Client *IDL_RPCInit(long ServerId, char* pHostname)
Use this function to initialize an IDL RPC client session.
The client program is registered as a client of the IDL RPC server. The server that the client is registered with depends on the values of the parameters passed to the function.
The ID number of the IDL server that the program is to be registered with. If this value is 0, the default server ID (0x2010CAFE) is used.
This is the name of the machine where the IDL server is running. If this value is NULL or “”, the default, “localhost”, is used.
A pointer to the new CLIENT structure is returned upon successful completion. This opaque data structure is then later used by the client program to perform operations with the server. This function returns NULL if the operation was unsuccessful.
Client *IDL_RPCInitWithLoopback(long PortId, char pHostname)
Use this function to initialize an IDL RPC client session via the loopback interface.
The client program is registered as a client of the IDL RPC server. The server that the client is registered with depends on the values of the parameters passed to the function.
On the IDL server, the ID number of the port on which the program should be registered.
If this value is 0, the default port ID (0xC350) is used.
This is the name of the machine where the IDL server is running. If this value is NULL or “”, the default, “localhost”, is used.
A pointer to the new CLIENT structure is returned upon successful completion. This opaque data structure is then later used by the client program to perform operations with the server. This function returns NULL if the operation was unsuccessful.
char * IDL_RPCMakeArray( int type, int n_dim, IDL_MEMINT dim[], int init, IDL_VPTR *var)
This function creates an IDL RPC client temporary array variable with a data area of the specified size.
The IDL type code for the resulting array.
The number of array dimensions. The constant IDL_MAX_ARRAY_DIM defines the upper limit of this value.
A C array of IDL_MAX_ARRAY_DIM elements containing the array dimensions. The number of dimensions in the array is given by the n_dim argument.
This parameter specifies the sort of initialization that should be applied to the resulting array. init must be one of the following:
The address of an IDL_VPTR containing the address of the resulting IDL RPC client temporary variable.
On success, this function returns a pointer to the data area of the allocated array. The value returned is the same as is contained in the var->value.arr->data field of the variable. On failure, it returns NULL.
As with variables returned from IDL_RPCGettmp(), the variable allocated via this function must be de-allocated using IDL_RPCDeltmp() when the variable is no longer needed.
int IDL_RPCOutputCapture( CLIENT *pClient, int n_lines)
Use this routine to enable and disable capture of lines output from the IDL RPC server. Normally, IDL will write any output to the terminal on which the server was started. This function can be used to save this information so that the client program can request the lines sent to the output buffer.
A pointer to the CLIENT structure that corresponds to the desired IDL session.
If this value is less than or equal to zero, no output lines will be buffered in the IDL RPC server and output will be sent to the normal output device on the IDL RPC server. If the value of this parameter is greater than zero, the specified number of lines will be stored by the IDL RPC server.
This function returns 1 on success, or 0 on failure.
int IDL_RPCOutputGetStr(CLIENT *pClient, IDL_RPC_LINE_S *pLine, int first)
Use this function to get an output line from the line queue being maintained on the RPC server. The routine IDL_RPCOutputCapture() must have been called to initialize the output queue on the RPC server before this routine is called.
A pointer to the CLIENT structure that corresponds to the desired IDL session.
A pointer to a valid IDL_RPC_LINE_S structure. The buf field of this structure will contain the output string returned from the IDL RPC server and the flags field will be set to one of the following (from idl_export.h):
If first is set equal to a non-zero value, the first line is popped from the output buffer on the IDL RPC server (the output buffer is treated like a stack). If first is set equal to zero, the last line is de-queued from the output buffer (the output buffer is treated like a queue).
A true value (1) is returned upon success. A false value (0) is returned when there are no more lines available in the output buffer or when an RPC error is detected.
int IDL_RPCSetMainVariable( CLIENT *pClient, char *Name, IDL_VPTR pVar)
Use this routine to assign a value to a main level IDL variable in the IDL RPC server session referred to by pClient. If the variable does not already exist, a new variable will be created.
A pointer to the CLIENT structure that corresponds to the desired IDL session.
A pointer to the null-terminated name of the variable, which must be in upper-case.
A pointer to an IDL_VARIABLE structure that contains the value that the IDL RPC main level variable referenced by Name should be set to.
This function returns 1 on success, or 0 on failure.
int IDL_RPCSetVariable( CLIENT *pClient, char *Name, IDL_VPTR pVar)
Use this routine to assign a value to an IDL variable in the IDL RPC server session referred to by pClient. If the variable does not already exist, a new variable will be created. Unlike IDL_RPCSetMainVariable(), this routine sets the variable in the current IDL program scope.
A pointer to the CLIENT structure that corresponds to the desired IDL session.
A pointer to the null-terminated name of the variable, which must be in upper-case.
A pointer to an IDL_VARIABLE structure that contains the value that the IDL RPC variable referenced by Name should be set to.
This function returns 1 on success, or 0 on failure.
void IDL_RPCStoreScalar(IDL_VPTR dest, int type, IDL_ALLTYPES *value)
Use this function to store a scalar value into an IDL_VARIABLE structure. Before the scalar is stored, any dynamic part of the existing IDL_VARIABLE is de-allocated.
An IDL_VPTR to the IDL_VARIABLE in which the scalar should be stored.
The type code for the scalar value.
The address of an IDL_ALLTYPES union that contains the value to store.
None.
void IDL_RPCStrDelete(IDL_STRING *str, IDL_MEMINT n)
Use this function to delete a string.
void IDL_RPCStrDup(IDL_STRING *str, IDL_MEMINT n)
Use this function to duplicate a string.
void IDL_RPCStrEnsureLength(IDL_STRING *s, int n)
Use this function to check the length of a string.
void IDL_RPCStrStore( IDL_STRING *s, char *fs)
Use this function to store a string.
int IDL_RPCTimeout(long lTimeOut)
Use this function to set the timeout value used when the RPC client makes requests of the server.
A integer value, in seconds, specifying the timeout value that will be used in RPC
operations.
This function returns 1 on success, or 0 on failure.
void IDL_RPCVarCopy(IDL_VPTR src, IDL_VPTR dst)
Use this function to copy the contents of the src variable to the dst variable. Any dynamic memory associated with dst is de-allocated before the source data is copied. This function emulates the callable IDL function IDL_VarCopy().
The source variable to be copied. If this variable is marked as temporary (returned from IDL_RPCGettmp(), for example) the dynamic data will be moved rather than copied to the destination variable.
The destination variable that src is copied to.
None.
void IDL_RPCVarGetData(IDL_VPTR v, IDL_MEMINT *n, char **pd, int ensure_simple)
Use this function to obtain a pointer to a variable’s data, and to determine how many data elements the variable contains.
The variable for which data is desired.
The address of a variable that will contain the number of elements in v.
The address of a variable that will contain a pointer to v’s data, cast to be a pointer to pointer to char (e.g. (char **) &myptr).
If TRUE, this routine calls the ENSURE_SIMPLE macro on the argument v to screen out variables of the types it prevents. Otherwise, EXCLUDE_FILE is called, because file variables have no data area to return.
On exit, IDL_RPCVarGetData() stores the data count and pointer into the variables pointed at by n and pd, respectively.
The following macros can be used to get information on IDL RPC variables. These macros are defined in idl_rpc.h.
All of these macros accept a single argument, v, of type IDL_VPTR.
This macro returns a pointer (char*) to the data area of an array block.
This macro returns a C array which contains the array dimensions.
This macro returns the number of dimensions of the array.
This macro returns the value of a 1-byte, unsigned char variable.
This macro returns the value (as a struct, not a pointer) of a complex variable.
This macro returns the real field of a complex variable.
This macro returns the imaginary field of a complex variable.
This macro returns the value (as a struct, not a pointer) of a double precision, complex variable.
This macro returns the real field of a double-precision complex variable.
This macro returns the imaginary field of a double-precision complex variable.
This macro returns the value of a double-precision, floating-point variable.
This macro returns the value of a single-precision, floating-point variable.
This macro returns the value of a 2-byte integer variable.
This macro returns the value of a 4-byte integer variable.
This macro returns the value of a 8-byte integer variable.
This macro returns non-zero if v is an array variable.
This macro returns the value of a string variable (as a char*).
This macro returns the type code of the variable. IDL type codes are discussed in Type Codes.
This macro returns the value of an unsigned 2-byte integer variable.
This macro returns the value of an unsigned 4-byte integer variable.
This macro returns the value of an unsigned 8-byte integer value.